tsconfig-resolver

tsconfig-resolver

A tool for loading the nearest tsconfig file in the same way the TypeScript compiler does. It walks up the directory tree until it finds the first matching tsconfig.json file.

Table of Contents

• tsconfig-resolver
  • Table of Contents
  • Usage
    • Setup
    • Code Example
  • API
    • tsconfigResolver
      • Returns
      • Options
    • clearCache
    • CacheStrategy
    • TsConfigErrorReason
    • TsConfigJson
  • Contributing
  • Versioning
  • License
  • Contributors

Usage

tsconfig-resolver is designed to be used inside your node project.

Setup

First, install the plugin and it's peer dependencies:

npm install --save tsconfig-resolver

or

yarn add tsconfig-resolver

Code Example

The following will load the first tsconfig.json file working upwards from the process.cwd() of the running node process.

import { tsconfigResolver } from 'tsconfig-resolver';

const result = tsconfigResolver();

// without type narrowing
console.log(result?.config);

// with type narrowing
if (result.exists) {
  console.log(result.config);
}

Configuration options can also be passed into the export function.

import { tsconfigResolver, CacheStrategy } from 'tsconfig-resolver';
import { join } from 'path';

const result = tsconfig({
  cwd: join(__dirname, 'src'),
  fileName: 'tsconfig.prod.json',
  cacheStrategy: CacheStrategy.Directory,
});

API

tsconfigResolver

import { tsconfigResolver } from 'tsconfig-resolver';

Returns

The function returns an object consisting of the following.

Property	Type	Description
config	TsConfigJson or undefined	The configuration object. undefined when the tsconfig resolver failed and no configuration was found. TsConfigJson (exported by the type-fest library) when the resolved tsconfig has been found and loaded.
exists	boolean	Whether or not the configuration could be loaded. false when no tsconfig could be found. true when a valid tsconfig file has been found and successfully loaded.
reason	TsConfigErrorReason or undefined	The reason for failure. TsConfigErrorReason.NotFound when the config failure is because the filename has not been found. TsConfigErrorReason.InvalidConfig when the config failure is because of an invalid config. undefined when no failure has occurred.
path	string or undefined	The absolute path to the tsconfig.json or given filename. undefined when not found. string when config json is invalid. string when a valid tsconfig has been loaded.

Options

Property	Type	Default	Description
cwd	string	process.cwd()	The directory to start searching from.
fileName	string	'tsconfig.json'	Set the file name of the config file to search for.
cacheStrategy	string	CacheStrategy.Never	Set the caching strategy that will be used when searching for a file that's already been found.

clearCache

Clears the cache.

import { tsconfigResolver, clearCache } from 'tsconfig-resolver';

const result = tsconfigResolver();

// Now clear the cache.
clearCache();

CacheStrategy

import { CacheStrategy } from 'tsconfig-resolver';

Provides the available caching strategies that can be used.

Sometimes you'll want to run this module several times during runtime but it can be slow and expensive walk up the file tree for the tsconfig value every time.

To help prevent unnecessary lookups there are custom caching strategies available.

• CacheStrategy.Never - Caching never happens and the returned value is always recalculated
• CacheStrategy.Always - The first time the tsconfigResolver method is run it will save a cached value (by fileName) which will be returned every time after that. This value will always be the same.
• CacheStrategy.Directory - The cache will be used when the same directory (and fileName) is being searched.

TsConfigErrorReason

import { TsConfigErrorReason } from 'tsconfig-resolver';

This provides the reason for the error in resolving the tsconfig.

• TsConfigErrorReason.NotFound - The tsconfig file could not be found.
• TsConfigErrorReason.InvalidConfig - The file was found but the configuration was invalid.

TsConfigJson

Re-exported from type-fest.

Contributing

Dive into the codebase with Gitpod.

Versioning

This project uses SemVer for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the MIT License - see the LICENSE file for details

Contributors